﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>VarSetCapacity()</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="../css/commands.css" rel="stylesheet" type="text/css">
<link href="../css/print.css" rel="stylesheet" type="text/css" media="print">
</head>
<body>

<h1>VarSetCapacity()</h1>

<p>增大或释放一个变量所占据的内存空间。通常，这只在特殊情况才有必要，如 <a href="DllCall.htm">DllCall</a> 。</p>

<p class="CommandSyntax">GrantedCapacity := VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte])</p>
<h3>参数 </h3>
<table border="1" width="100%" cellspacing="0" cellpadding="3" bordercolor="#C0C0C0">
  <tr> 
    <td width="15%">GrantedCapacity</td>
    <td width="85%">现在变量所占据（可自由使用）的字符串长度，会大于等于 <em>RequestedCapacity</em> 。如果 <em>VarName</em> 不是一个合法的变量名（比如是一个原意的字符串或数字），将返回 0 。如果系统没有足够的内存完成更改（非常罕见），将显示一个错误框，随后 <a href="../misc/Threads.htm">当前线程</a> 会退出。</td>
  </tr>
  <tr>
    <td>UnquotedVarName</td>
    <td>变量名（<em>没有引号</em>）。举个例子： VarSetCapacity(MyVar, 1000) 。这也可以是个动态变量例如 Array%i% 或一个 <a href="../Functions.htm#ByRef">函数的引用(ByRef)参数</a>。</td>
  </tr>
  <tr>
    <td>RequestedCapacity</td>
    <td><p>如果省略，将返回变量的当前容量且其内容不变。否则，变量内的所有内容将丢失（变量会变空）。</p>
      <p>指定 <em>RequestedCapacity</em> 为变量在调整后应该能够占据的字符串长度。该长度不包括内部的零结束符。举个例子，指定 1 将允许变量占有最多一个字符外加零结束符。注：若以后脚本为该变量分配一个更大的值，它将自动扩展。</p>      
      <p>经常调用该函数可以简单地确保变量拥有一个最小容量，由于性能原因，该函数只在 <em>RequestedCapacity</em> 为 0 时缩小变量的容量。换句话说，如果变量的容量已经大于 <em>RequestedCapacity</em> ，则不会减小（不过为了保持一致，变量仍然会变空）。</p>
      <p>因此，要明确地缩小一个变量，首先用 <em>VarSetCapacity(Var, 0)</em> 释放它的内存，然后用 <em>VarSetCapacity(Var, NewCapacity) —— </em>或者简单地让它根据需要从零自动扩展。</p>
      <p>由于性能原因，释放一个原先容量在 1 与 63 之间的变量可能没有效果，因为它的内存是永久性的。在这种情况下，函数将返回当前容量而不是 0 。</p>
      <p>由于性能原因，将空字符串赋值给一个容量小于 4096 的变量将不会释放它的内存（如 <em>Var := &quot;&quot;</em>）。然而，<em>VarSetCapacity(Var, 0)</em> 会释放。</p>
      <p><a name="neg1"></a>在 v1.0.44.03 及以后版本中，指定 <em>RequestedCapacity</em> 为 -1 可以将变量内部存储的长度更新为当前内容的长度。在变量会被间接修改的地方这很有用，例如通过 <a href="DllCall.htm">DllCall()</a> 传入它的 <a href="../Variables.htm#amp">地址</a>。在这种模式下，VarSetCapacity() 会返回变量的长度而不是容量。</p></td>
  </tr>
  <tr>
    <td>FillByte</td>
    <td>该参数通常省略，表示目标变量的内存不会被初始化（或者说，变量只是简单地像前面说的那样被置空）。否则，指定一个 0 到 255 之间的数。目标变量内存区域（它的当前容量）内的每一个字节都会被设为该数。0 是目前为止最常用的值，在将要存放原始二进制数据到变量里（比如一个 <a href="DllCall.htm#struct">DllCall 结构体</a> ）的地方这是很有用的。</td>
  </tr>
</table>

<h3>注意</h3>
<p>关于它的用法除了在 <a href="DllCall.htm#str">DllCall</a> 中所描述的以外，该函数还可以用于提升用逐步串联的方法构造一个字符串时的性能。这是因为当你可以确定字符串的最终大小时可以避免多次的自动大小调整。在这种情况下， <em>RequestedCapacity</em> 不必太精确：如果容量太小，仍然能够提升性能，并且当容量耗尽时变量会开始自动扩展。如果容量太大，会浪费一些内存，不过只是暂时的，因为在操作完成之后可以通过 <em>VarSetCapacity(Var, 0)</em> 或 <em>Var := &quot;&quot;</em> 等方法来释放所有的内存。</p>
<p><a href="_MaxMem.htm">#MaxMem</a> 只会限制一个变量主动地自动扩展。它不会影响 <a href="VarSetCapacity.htm">VarSetCapacity</a> 。</p>
<h3>相关命令</h3>
<p><a href="DllCall.htm">DllCall</a>, <a href="_MaxMem.htm">#MaxMem</a></p>
<h3>示例</h3>
<pre class="NoIndent">VarSetCapacity(MyVar, 10240000)  <em>; ~10 MB</em>
Loop
{
    ...
    MyVar = %MyVar%%StringToConcatenate%
    ...
}</pre>

</body>
</html>
